💰 API de Sistema Financeiro - Documentação Completa

📋 Visão Geral

O Sistema Financeiro do CordenaAi é responsável pela gestão completa de produtos, cobranças, pagamentos e extratos financeiros. Permite vincular produtos a diferentes entidades de cobrança, gerenciar débitos e créditos, e manter um histórico completo de transações financeiras dos usuários.

🎯 Funcionalidades Principais

🎯 Endpoints Disponíveis

📦 1. PRODUTOS - Gestão de Produtos/Serviços

1.1. GET /api/produtos

Listar Todos os Produtos

1.2. GET /api/produtos/ativos

Listar Apenas Produtos Ativos

1.3. GET /api/produtos/{id}

Obter Produto por ID

1.4. POST /api/produtos

Criar Novo Produto

1.5. PUT /api/produtos/{id}

Atualizar Produto

1.6. DELETE /api/produtos/{id}

Excluir Produto (Soft Delete)

💳 2. COBRANÇAS - Gestão de Entidades de Cobrança

2.1. GET /api/cobrancas

Listar Todas as Cobranças

2.2. GET /api/cobrancas/ativas

Listar Apenas Cobranças Ativas

2.3. GET /api/cobrancas/{id}

Obter Cobrança por ID

2.4. POST /api/cobrancas

Criar Nova Cobrança

2.5. PUT /api/cobrancas/{id}

Atualizar Cobrança

2.6. DELETE /api/cobrancas/{id}

Excluir Cobrança (Soft Delete)

🔗 3. PRODUTO-COBRANÇA - Gestão de Vínculos

3.1. GET /api/produto-cobranca

Listar Todos os Vínculos

3.2. GET /api/produto-cobranca/produto/{idProduto}

Listar Vínculos por Produto

3.3. GET /api/produto-cobranca/cobranca/{idCobranca}

Listar Vínculos por Cobrança

3.4. POST /api/produto-cobranca

Criar Vínculo Produto-Cobrança

3.5. DELETE /api/produto-cobranca/{id}

Remover Vínculo

📊 4. EXTRATO - Gestão de Movimentações Financeiras

4.1. POST /api/extrato/gerar-cobranca

Gerar Cobrança (Débito)

4.2. POST /api/extrato/registrar-pagamento

Registrar Pagamento (Crédito)

4.3. GET /api/extrato/usuario/{uuid}

Obter Extrato Completo do Usuário

4.4. GET /api/extrato/usuario/{uuid}/periodo

Obter Extrato por Período

4.5. GET /api/extrato/usuario/{uuid}/saldo

Calcular Saldo do Usuário

🧾 5. FATURA - Consolidação de Movimentações

5.1. GET /api/fatura/{uuid}

Gerar Fatura do Mês Atual

5.2. GET /api/fatura/{uuid}/{mes}/{ano}

Gerar Fatura de Período Específico

🔧 Modelos de Dados

Estrutura: Produto

{
  "id": 1,
  "nome": "Mensalidade Premium",
  "descricao": "Mensalidade mensal com benefícios extras",
  "valor": 150.00,
  "ativo": true,
  "dataCriacao": "2025-10-01T10:00:00",
  "dataAtualizacao": "2025-10-01T10:00:00"
}

Estrutura: Cobrança

{
  "id": 1,
  "descricao": "Conta Principal - PIX",
  "tipoConta": 0,
  "tipoPessoa": 0,
  "ordemPgto": 1,
  "tipoChavePix": 0,
  "chavePix": "123.456.789-00",
  "banco": "001",
  "agencia": "1234",
  "conta": "12345-6",
  "regraPagamento": "Pagamento até dia 10",
  "ativo": true,
  "dataCriacao": "2025-10-01T10:00:00",
  "dataAtualizacao": "2025-10-01T10:00:00"
}

Estrutura: Extrato

{
  "id": 1,
  "uuid_Usuario": "abc-123-def-456",
  "idProduto": 1,
  "nomeProduto": "Mensalidade Premium",
  "idCobranca": 1,
  "descricaoCobranca": "Conta Principal - PIX",
  "tipoMovimento": 0,
  "tipoMovimentoTexto": "Debito",
  "valor": 150.00,
  "descricao": "Mensalidade Outubro/2025",
  "dataReferencia": "2025-10-01",
  "dataMovimento": "2025-10-01T10:00:00",
  "status": 0,
  "statusTexto": "Pendente",
  "idPagamentoRelacionado": null,
  "observacao": null
}

Estrutura: Fatura

{
  "uuidUsuario": "abc-123-def-456",
  "mesReferencia": 10,
  "anoReferencia": 2025,
  "dataGeracao": "2025-10-07T10:30:00",
  "cobrancas": [
    {
      "id": 1,
      "produto": "Mensalidade Premium",
      "valor": 150.00,
      "data": "2025-10-01",
      "status": "Pendente",
      "descricao": "Mensalidade Outubro/2025"
    }
  ],
  "pagamentos": [
    {
      "id": 2,
      "produto": "Mensalidade Premium",
      "valor": 150.00,
      "data": "2025-10-05",
      "status": "Pago",
      "descricao": "Pagamento via PIX"
    }
  ],
  "resumo": {
    "totalCobrancas": 150.00,
    "totalPagamentos": 150.00,
    "saldo": 0.00
  }
}

📈 Enums do Sistema

TipoConta

TipoPessoa

TipoChavePix

TipoMovimento

StatusMovimento

🔐 Autenticação e Autorização

⚠️ IMPORTANTE: Todos os endpoints do sistema financeiro requerem autenticação JWT:

🔄 Fluxo Completo do Sistema Financeiro

📋 FASE 1: Configuração Inicial

Passo 1.1: Criar Produtos

POST /api/produtos
Content-Type: application/json
Authorization: Bearer {token}

{
  "nome": "Mensalidade Quadra",
  "descricao": "Mensalidade mensal uso da quadra",
  "valor": 100.00,
  "ativo": true
}

→ Resposta: Produto ID 1 criado

Passo 1.2: Criar Cobranças (Contas Destino)

POST /api/cobrancas
Content-Type: application/json
Authorization: Bearer {token}

{
  "descricao": "Conta PIX Principal",
  "tipoConta": 0,
  "tipoChavePix": 0,
  "chavePix": "123.456.789-00",
  "banco": "001",
  "agencia": "1234",
  "conta": "12345-6",
  "ativo": true
}

→ Resposta: Cobrança ID 1 criada

Passo 1.3: Vincular Produto à Cobrança

POST /api/produto-cobranca
Content-Type: application/json
Authorization: Bearer {token}

{
  "idProduto": 1,
  "idCobranca": 1
}

→ Resposta: Vínculo criado com sucesso
→ AGORA o Produto 1 pode gerar cobranças para Cobrança 1

💰 FASE 2: Geração de Cobranças

Passo 2.1: Gerar Cobrança Mensal para Usuário

POST /api/extrato/gerar-cobranca
Content-Type: application/json
Authorization: Bearer {token}

{
  "userId": "user-abc-123",
  "produtoCobrancaId": 13,
  "referencia": "Mensalidade Outubro/2025",
  "dataVencimento": "2025-10-31"
}

→ Sistema valida:
  ✓ Vínculo produto-cobrança existe e está ativo
  ✓ Produto vinculado existe e está ativo
  ✓ Cobrança vinculada existe e está ativa
  ✓ UserId é válido

→ Sistema obtém automaticamente:
  ✓ Valor: 100.00 (do produto)
  ✓ Descrição: "Cobrança - Mensalidade Quadra" (gerada automaticamente)

→ Cria no Extrato:
  - Tipo: Débito (+)
  - Valor: +100.00 (automático)
  - Descrição: "Cobrança - Mensalidade Quadra" (automática)
  - Status: Pendente
  
→ SALDO DO USUÁRIO: +100.00 (devedor)

✅ FASE 3: Registro de Pagamentos

Passo 3.1: Usuário Realiza Pagamento

POST /api/extrato/registrar-pagamento
Content-Type: application/json
Authorization: Bearer {token}

{
  "userId": "user-abc-123",
  "valor": 100.00,
  "descricao": "Pagamento via PIX",
  "referencia": "PIX_20251005_001"
}

→ Sistema valida:
  ✓ UserId é válido
  ✓ Valor > 0
  ✓ Descrição fornecida
  
→ Cria no Extrato:
  - Tipo: Crédito (-)
  - Valor: -100.00
  - Status: Pago
  - ProdutoId: NULL (pagamento geral)
  - Processado: true (automático)
  
→ SALDO DO USUÁRIO: +100 -100 = 0.00 (quitado)

🧾 FASE 4: Consulta de Extrato e Fatura

Passo 4.1: Consultar Extrato Completo

GET /api/extrato/usuario/user-abc-123
Authorization: Bearer {token}

→ Retorna:
[
  {
    "id": 1,
    "tipoMovimento": 0,
    "tipoMovimentoTexto": "Debito",
    "valor": 100.00,
    "status": 1,
    "statusTexto": "Pago",
    "dataMovimento": "2025-10-01T10:00:00"
  },
  {
    "id": 2,
    "tipoMovimento": 1,
    "tipoMovimentoTexto": "Credito",
    "valor": 100.00,
    "status": 1,
    "statusTexto": "Pago",
    "idPagamentoRelacionado": 1,
    "dataMovimento": "2025-10-05T14:30:00"
  }
]

Passo 4.2: Consultar Saldo do Usuário

GET /api/extrato/usuario/user-abc-123/saldo
Authorization: Bearer {token}

→ Retorna:
{
  "status": true,
  "message": "Saldo calculado com sucesso",
  "data": 0.00
}

→ Cálculo automático:
  Total Cobranças: 100.00
  Total Pagamentos: 100.00
  Saldo: 100.00 - 100.00 = 0.00

Passo 4.3: Gerar Fatura Mensal

GET /api/fatura/user-abc-123/10/2025
Authorization: Bearer {token}

→ Retorna:
{
  "uuidUsuario": "user-abc-123",
  "mesReferencia": 10,
  "anoReferencia": 2025,
  "dataGeracao": "2025-10-07T10:30:00",
  "cobrancas": [
    {
      "id": 1,
      "produto": "Mensalidade Quadra",
      "valor": 100.00,
      "data": "2025-10-01",
      "status": "Pago"
    }
  ],
  "pagamentos": [
    {
      "id": 2,
      "produto": "Mensalidade Quadra",
      "valor": 100.00,
      "data": "2025-10-05",
      "status": "Pago"
    }
  ],
  "resumo": {
    "totalCobrancas": 100.00,
    "totalPagamentos": 100.00,
    "saldo": 0.00  ← QUITADO!
  }
}

📊 Casos de Uso Avançados

Caso 1: Múltiplos Produtos para Mesmo Usuário

// Gerar cobrança de Mensalidade
POST /api/extrato/gerar-cobranca
{
  "userId": "user-123",
  "produtoCobrancaId": 21,  // ID do vínculo (Mensalidade → Conta PIX)
  "referencia": "Mensalidade Outubro/2025"
  // Valor e descrição automáticos do produto
}

// Gerar cobrança de Aluguel Churrasqueira
POST /api/extrato/gerar-cobranca
{
  "userId": "user-123",
  "produtoCobrancaId": 22,  // ID do vínculo (Churrasqueira → Conta PIX)
  "referencia": "Aluguel Churrasqueira Outubro/2025"
  // Valor e descrição automáticos do produto
}

→ Fatura do mês:
  Total Cobranças: 150.00
  (100.00 + 50.00)

Caso 2: Pagamento Parcial

// Cobrança de 100.00 (automática do produto)
POST /api/extrato/gerar-cobranca
{
  "userId": "user-123",
  "produtoCobrancaId": 21
  // Valor automático: 100.00
}

// Pagamento parcial de 50.00
POST /api/extrato/registrar-pagamento
{
  "userId": "user-123",
  "valor": 50.00,
  "descricao": "Pagamento parcial via PIX"
}

→ Saldo: 100.00 - 50.00 = 50.00 (ainda devedor)

Caso 3: Produto com Múltiplas Cobranças

// Vincular Produto a múltiplas contas
POST /api/produto-cobranca
{ "idProduto": 1, "idCobranca": 1 }

POST /api/produto-cobranca
{ "idProduto": 1, "idCobranca": 2 }

// Ao gerar cobrança, escolher qual conta recebe
POST /api/extrato/gerar-cobranca
{
  "userId": "user-123",
  "produtoCobrancaId": 21,  // Escolha o ID do vínculo desejado
  "referencia": "Mensalidade Outubro/2025"
  // Valor e descrição automáticos do produto
}

⚠️ Validações e Regras de Negócio

Validações de Produto

Validações de Cobrança

Regras de Vínculo

Regras de Cobrança

Regras de Pagamento

Regras de Cálculo de Saldo

Fórmula: Saldo = Σ(Débitos) - Σ(Créditos)

Exemplo 1 (Quitado):
  Débito: +100.00
  Crédito: -100.00
  Saldo: 0.00

Exemplo 2 (Devedor):
  Débito: +100.00
  Crédito: -50.00
  Saldo: +50.00

Exemplo 3 (Credor - pagou a mais):
  Débito: +100.00
  Crédito: -150.00
  Saldo: -50.00 (usuário tem crédito)

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Resposta de Erro

{
  "message": "Produto não encontrado ou inativo",
  "status": false
}

Exemplos de Erros Comuns

Erro: Produto não vinculado à cobrança

POST /api/extrato/gerar-cobranca
{
  "userId": "user-123",
  "produtoCobrancaId": 999,  // ID inexistente ou desvinculado
  ...
}

→ 400 Bad Request
{
  "message": "Vínculo produto-cobrança com ID 999 não encontrado ou inativo."
}

Erro: Produto inativo

POST /api/extrato/gerar-cobranca
{
  "userId": "user-123",
  "produtoCobrancaId": 21,  // Produto vinculado está inativo
  ...
}

→ 400 Bad Request
{
  "message": "Produto 'Mensalidade Premium' está inativo e não pode ser cobrado."
}

Erro: Vínculo duplicado

POST /api/produto-cobranca
{
  "idProduto": 1,
  "idCobranca": 1
}

→ 400 Bad Request
{
  "message": "Este vínculo já existe"
}

Erro: UserId obrigatório

POST /api/extrato/gerar-cobranca
{
  "produtoCobrancaId": 21
  // UserId ausente
}

→ 400 Bad Request
{
  "errors": {
    "UserId": ["O ID do usuário é obrigatório."]
  }
}

Erro: Token JWT ausente

GET /api/extrato/usuario/user-123/saldo
// Sem header Authorization

→ 401 Unauthorized
{
  "message": "Token de autenticação ausente ou inválido"
}

📈 Performance e Limitações

Limitações

Otimizações Implementadas

🔄 Integração com Outros Módulos

Módulos Relacionados

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

🔧 Correções e Melhorias Implementadas

✅ Segurança

✅ Geração Automática de Cobrança

✅ Registro de Pagamentos

✅ Cálculo de Saldo

✅ Entity Framework

✅ API Simplificada

📚 Resumo Executivo

🎯 O Sistema em 5 Passos

  1. CONFIGURAR: Criar produtos, cobranças e vínculos
  2. COBRAR: Gerar débitos para usuários
  3. PAGAR: Registrar créditos (pagamentos)
  4. CONSULTAR: Visualizar extrato e saldo
  5. ANALISAR: Gerar faturas consolidadas

📊 Conceitos-Chave

✅ Checklist de Uso

□ Criar pelo menos 1 produto
□ Criar pelo menos 1 cobrança (conta destino)
□ Vincular produto à cobrança
□ Gerar cobrança (débito) para usuário
□ Registrar pagamento (crédito) do usuário
□ Consultar extrato/fatura do usuário

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi